Documentation -- Sidebar Contribution Design Pattern and Migrating a Sametime 7.5 plugin over to Notes 8

Notes/Domino 8 Forum

Subject:

Sidebar Contribution Design Pattern

This document discusses the Notes 8 “shelfViews” programming model, and explicitly explains how to contribute a shelf view to the Notes 8 sidebar. There are basically two steps:

Create a view and add a contribution to the org.eclipse.ui.views extension point.
Contribute the view to the com.ibm.rcp.ui.shelfViews extension point to have it appear in the sidebar.

Following these descriptions, we compare the Notes 8 “shelfViews” programming model to the Sametime “miniApps” programming models, such that developers will know how to migrate a plugin from the Sametime client to the Notes 8 client.

The Notes 8 “shelfViews” Programming Model
Notes 8 makes use of the eclipse IViewPart interface to be able to tie each shelf view to the workbench. Each view part has a view site that connects the part to the workbench, allowing the view to register any global actions with the site’s action bars, including access to its own panel menu, a local toolbar, and the status line. The view can also register any context menus with the site, or register a selection provider to allow the workbench’s ISelectionService to include the part in its tracking. The workbench also provides other capabilities, such as saving the state of the view, or activating these shelf views upon accessibility.

When creating a view to be shown in a Notes 8 shelf view, the class should either implement the interface, org.eclipse.ui.IViewPart, or subclass the abstract class, org.eclipse.ui.part.ViewPart. Subclassing ViewPart is the suggested method, to save the developer from implementing the view from scratch. Subclasses of ViewPart must implement the following methods:

createPartControl(Composite parent) – to create the view’s controls
setFocus() – to receive focus

After creating the class, a contribution to the org.eclipse.ui.views extension point must be added to the plugin.xml file for the plugin, as seen in the following example:

<extension
point="org.eclipse.ui.views">
<view
name="BuddyNote"
icon="images/ST_Ext_Buddy_Note.png"
class="com.ibm.collaboration.realtime.sample.buddynote.BuddyNoteMiniApp "
id="com.ibm.collaboration.realtime.sample.buddynote.buddynoteminiapp">
</view>
</extension>

Make sure the following attributes are specified:

The “name” attribute describes the String to be displayed in the titlebar.
The “id” attribute is the unique identifier of the view. This is also what is used to refer to the view when contributing to the shelfViews extension point.
The “class” attribute specifies what class is referenced in this extension
The “icon” attribute describes the icon to be displayed in the top left corner of the titlebar. The standard size is 16x16 pixels.

The view should be optimally viewed in a frame approximately 186 pixels wide. The view is also resizeable. Thus, make sure the content can be scrolled (if applicable), and any toolbars do not get cut off, or have chevrons pointing to more actions.

Contributing to the shelfViews extension point

In the plugin where the view is defined, add an extension to the com.ibm.rcp.ui.shelfViews extension point as demonstrated in the following example:


<extension
point="org.eclipse.ui.views">
<view
name="BuddyNote"
icon="images/ST_Ext_Buddy_Note.png"
class="com.ibm.collaboration.realtime.sample.buddynote.BuddyNoteMiniApp "
id="com.ibm.collaboration.realtime.sample.buddynote.buddynoteminiapp">
</view>
</extension>


<extension
point="com.ibm.rcp.ui.shelfViews">
<shelfView
id="buddynote"
view="com.ibm.collaboration.realtime.sample.buddynote.buddynoteminiapp"
region="MIDDLE"
page="RIGHT"
showTitle="true"/>
</extension>


Note that the com.ibm.rcp.platform.shelfViews extension point has been deprecated.

The “id” attribute uniquely identifies the shelf view. Thus, if the same id is used more than once, only one of those views will be registered.

The “view” attribute corresponds to the “id” specified in the view contribution.

The “region” attribute is an optional means of describing what area of the sidebar the view should belong to. Possible values are “TOP,” “MIDDLE,” and “BOTTOM.” Items within the same placeholder region will be ordered based on when the view gets loaded. Thus, the contributor of the view cannot control the placing of views within the same placeholder region. If nothing is specified, the view will automatically be placed on the bottom.

The “page” attribute describes which sidebar the view should belong. For Notes 8, the value “RIGHT” should be specified such that the view appears in the sidebar on the right side of the client.

The “showTitle” attribute describes whether or not the titlebar should be shown. For Notes 8, a value of “true” should be specified such that all views in the sidebar have a titlebar and look uniform.

Notes 8 “shelfViews” vs. Sametime 7.5 “miniApps”

Similar to Notes 8’s use of eclipse’s IViewPart interface and ViewPart abstract class for its shelf views, Sametime 7.5 uses the abstract class, com.ibm.collaboration.realtime.miniapp.AbstractMiniApp, to create the views displayed in the Sametime client. The API for AbstractMiniApp and ViewPart are similar but have some important differences, as seen in the following selection of the API:

AbstractMiniApp API	Corresponding ViewPart API
public AbstractMiniApp(); public abstract Control createControl(Composite arg0); public IWorkbenchPartSite getSite(); public abstract void init() throws Exception; public Boolean isInitiallyVisible(); public void setSite(IWorkbenchPartSite site);	public ViewPart(); public abstract void createPartControl(Composite arg0); public IViewSite getViewSite(); public void init(IViewSite site) throws PartInitException; public void init(IViewSite site, IMemento memento) throws PartInitException; public void setSite(IWorkbenchPartSite site);

As mentioned earlier, a ViewPart has a createPartControl(Composite) method in which the view’s controls are created. Similarly, an AbstractMiniApp has a corresponding method, createControl(Composite). Unlike the ViewPart, however, the AbstractMiniApp does not require a view site upon initialization. The ViewPart must have a view site in order to tie the part to the workbench, thus it is a parameter in the init methods. Since the Sametime views do not require that upon initialization, the Sametime views are rather independent parts of the Sametime workbench, and are not connected to workbench-related features, such as the action bars mentioned previously.

As a result of these differences, it will be somewhat seamless to migrate a Sametime mini app to Notes 8, but not necessarily vice versa. A mini app class has the basics needed to support a ViewPart, but a ViewPart may be supporting connections to workbench-related capabilities that will not be supported if placed in the Sametime client.

Steps for Migrating a Sametime 7.5 plugin over to Notes 8

1. In the plugin.xml of the Sametime plugin, find the extension to the com.ibm.collaboration.realtime.imhub.miniApps extension point. Find the source code for the class specified in the “class” attribute. In the following example, this would be the TaskListMiniApp.java file located in the com.ibm.webahead.stplugins.tasklist.plugin package.

<extension
point="com.ibm.collaboration.realtime.imhub.miniApps">
<miniApp
class="com.ibm.webahead.stplugins.tasklist.plugin.TaskListMiniApp"
displayName="TaskList"
icon="images/Group.gif"
id="TaskList"
maxHeight="400"/>
</extension>

2. If the class extends org.eclipse.ui.part.ViewPart, no changes need to be made, and you may skip to step #4. If it extends com.ibm.collaboration.realtime.miniApp.AbstractMiniApp instead, replace AbstractMiniApp with ViewPart, and import the required methods. A createControl(Composite parent) method should already exist. Modify the newly added createPartControl(Composite parent) method to call createControl(parent).

3. Go back to the plugin.xml file. Add an extension to the org.eclipse.ui.views extension point.

<extension
point="org.eclipse.ui.views">
<view
class="com.ibm.webahead.stplugins.tasklist.plugin.TaskListMiniApp"
id="com.ibm.webahead.stplugins.tasklist.plugin.view"
name="Task List"/>
</extension>

Notice that the “class” attributes for both the miniApps extension point and views extension point are the same. The “name” attribute is the string that will be displayed in the titlebar of the panel. The “id” attribute is the unique identifier, and will be used to identify the view when contributing to the shelfViews extension point.

4. Finally, add an extension to the com.ibm.rcp.ui.shelfViews extension point, detailed further in the section “Contributing to the shelfViews extension point” section.

Migrating a Sametime 7.5.1 plugin over to Notes 8

Sametime 7.5.1 plugins follow the Notes 8 shelfViews programming model. Thus, no further changes should have to be made and installing the plugin should be sufficient.

Installing new plugins in Notes 8

By default, the policy for enabling the display for the user-initiated updates application install menu is set to false (hidden). When set to true, the menu will be rendered visible. This can be updated using the Domino 8.0 desktop policy as described in the Beta 2 release notes.

In cases where Domino is not deployed, it is possible to manually enable this setting on the client. This can be done by updating the <notes_home>\framework\rcp\plugin_customization.ini file to include the following property: com.ibm.notes.branding/enable.update.ui=true.

The value specified in the plugin_customization.ini file acts as a default value when no policy has been set. If the Domino desktop policy sets the user-initiated updates preference, it can be locked-down and will override any existing value specified in the plugin_customization.ini file.

When the enable.update.ui preference is set to true, users will see the following Install and Application Management menu items shown in the screenshot below. Please note that the location of these menu items may change for the general release.